---
title: 数値書式
---

スプレッドシートの数値書式機能は、数値の表示方法を制御するためのものです。小数点以下桁数、桁区切り（千位区切り）、パーセンテージ、通貨記号など、数値の表示形式をカスタマイズできます。適切な数値書式を設定することで、データをより読みやすく、理解しやすくできます。

<Callout type="warning" title="注意事項">
  **DBNum 構文** には対応していません。
</Callout>

## 使い方

UI ではメニューバーからセルの数値書式を設定できます。あるいはセルデータ [`ICellData`](/guides/sheets/model/cell-data) オブジェクト内の [`s.n.pattern`](/guides/sheets/model/cell-data#number-format) フィールドを設定します。

```typescript
const data = {
  v: 123456.789,
  s: {
    n: {
      pattern: '#,##0.00',
    },
  },
}
```

**既定では、先頭が 0 のテキストや、日付形式に変換可能な数値は自動的に対応する数値書式に変換されます。**

この自動変換を避けたい場合、以下のいずれかを行ってください:

1. セルの数値書式をテキスト形式に設定する。

```typescript
import { DEFAULT_TEXT_FORMAT_EXCEL } from '@univerjs/engine-numfmt'

const data = {
  v: '012.0',
  s: {
    n: {
      pattern: DEFAULT_TEXT_FORMAT_EXCEL, // テキスト形式
    },
  },
}
```

または Facade API でセル書式を設定:

```typescript
fRange.setNumberFormat(DEFAULT_TEXT_FORMAT_EXCEL)
```

2. 入力時に数値の前へシングルクォート（`'`）を付ける（[テキストとして扱う強制](/guides/sheets/model/cell-data#cell-type)）。

## Facade API

### 数値書式の設定

詳細なパラメータ仕様: https://support.microsoft.com/en-us/office/number-format-codes-5026bbd6-04bc-48cd-bf33-80f18b4eae68

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1 セルの数値書式を '#,##0.00' に設定
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')
fRange.getDisplayValue() // 1,234.57
```

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:B2 範囲の数値書式をまとめて設定
const fRange = fWorksheet.getRange('A1:B2')
fRange.setValues([
  [1234.567, 0.1234],
  [45658, 0.9876],
]).setNumberFormats([
  ['#,##0.00', '0.00%'],
  ['yyyy-MM-DD', ''],
])
fRange.getDisplayValues() // [['1,234.57', '12.34%'], ['2025-01-01', 0.9876]]
```

### 数値書式の取得

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:B2 範囲の左上セルの数値書式を取得
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormat()
```

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()

// A1:B2 範囲内の各セルの数値書式を取得
const fRange = fWorksheet.getRange('A1:B2')
fRange.getNumberFormats()
```

### 数値書式のロケール設定

[`FWorkbook.setNumfmtLocal(local)`](https://reference.univer.ai/en-US/classes/FWorkbook#setnumfmtlocal) を使用して数値書式のロケールを設定できます。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1')
fRange.setValue(1234.567).setNumberFormat('#,##0.00')

// en_US ロケールを適用
fWorkbook.setNumfmtLocal('en_US')
fRange.getDisplayValue() // 1,234.57

// de_DE ロケールを適用
fWorkbook.setNumfmtLocal('de_DE')
fRange.getDisplayValue() // 1.234,57
```

## テキスト形式アラートとマークの無効化

`UniverSheetsNumfmtPlugin` では `disableTextFormatAlert` と `disableTextFormatMark` を設定して、セルのテキスト形式に関するアラート表示およびマーク表示を無効化できます。

```typescript
// プリセット設定
const { univerAPI } = createUniver({
  // ...
  presets: [
    UniverSheetsCorePreset({
      disableTextFormatAlert: true,
      disableTextFormatMark: true,
    }),
  ],
})
```

```typescript
// プラグイン設定
univer.registerPlugin(UniverSheetsNumfmtPlugin, {
  disableTextFormatAlert: true,
  disableTextFormatMark: true,
})
```
